/*
 * The MIT License
 * 
 * Copyright (c) 2008 Comcast Interactive Media
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package cim.sf.core.command;

import org.osgi.framework.Bundle;

/**
 * A service that tracks registered commands and provides info and the
 * ability to execute them.
 * 
 * @author <a href="mailto:jeremy_volkman@cable.comcast.com">Jeremy Volkman</a>
 *
 */
public interface CommandShell {
    
    /**
     * Return a list of all command paths currently registered.
     * @return Currently registered command paths, lexicographically.
     */
    public String[] getCommands();
    
    /**
     * Return the description of the command at the given path.
     * @param commandPath The command path
     * @return The command description, or <code>null</code> if there
     * is no command with the given name or the command with the given
     * name has no description.
     */
    public String getCommandDescription(String commandPath) throws CommandNotFoundException;

    /**
     * Return the usage of the command at the given path.
     * @param commandPath The command path
     * @return The command usage, or <code>null</code> if there
     * is no command with the given name or the command with the given
     * name has no usage specification.
     */
    public String[] getCommandUsage(String commandPath) throws CommandNotFoundException;

    /**
     * Return the Bundle that provides the command at the given path
     * @param commandPath The command path
     * @return The providing Bundle.
     */
    public Bundle getCommandBundle(String commandPath) throws CommandNotFoundException;
    
    /**
     * Execute the command at the given path with the given CommandInvocation
     * object.
     * @param commandPath The path of the command to execute.
     * @param ci The CommandInvocation to execute with.
     * @throws CommandNotFoundException if the specified command does not exist.
     * @return The command's return status
     */
    public int executeCommand(String commandPath, CommandInvocation ci) throws CommandNotFoundException;
}
